CDicObj Class

CDicObj is an associative array of variants. Each item is associated with a unique key. The key is used to retrieve an individual item.

Example

' // Creates an instance of the CDicObj class
DIM pDic AS CDicObj

' // Adds some key, value pairs
pDic.Add "a", "Athens"
pDic.Add "b", "Belgrade"
pDic.Add "c", "Cairo"

print "Count: "; pDic.Count
print pDic.Exists("a")
print

' // Retrieve an item and display it
print pDic.Item("b")
print

' // Change key "b" to "m" and "Belgrade" to "México"
pDic.Key("b") = "m"
pDic.Item("m") = "México"
print pDic.Item("m")
print

' // Get all the items and display them
DIM dvItems AS DVARIANT = pDic.Items
FOR i AS LONG = dvItems.GetLBound TO dvItems.GetUBound
  print dvItems.GetVariantElement(i)
NEXT
print

' // Get all the keys and display them
DIM dvKeys AS DVARIANT = pDic.Keys
FOR i AS LONG = dvKeys.GetLBound TO dvKeys.GetUBound
  print dvKeys.GetVariantElement(i)
NEXT
print

' // Remove key "m"
pDic.Remove "m"
IF pDic.Exists("m") THEN PRINT "Key m exists" ELSE PRINT "Key m doesn't exist"

' // Remove all keys
pDic.RemoveAll
print "All the keys must have been deleted"
print "Count: "; pDic.Count
print

Include file: CDicObj.inc

Methods and Properties

Error and result codes

GetErrorInfo

Returns a localized description of the specified error code. If the error is omited, it will return the value returned by the Windows API function GetLastError.

PRIVATE FUNCTION GetErrorInfo (BYVAL nError AS LONG = -1) AS DWSTRING

GetLastResult

Returns the last result code

FUNCTION GetLastResult () AS HRESULT

SetResult

Sets the last result code.

FUNCTION SetResult (BYVAL Result AS HRESULT) AS HRESULT

Add

Adds a key and item pair to the associtive array.

FUNCTION Add (BYREF dvKey AS DVARIANT, BYREF dvItem AS DVARIANT) AS HRESULT

Return value

An error occurs if the key already exists.

Count

Returns the number of items in the associative array.

FUNCTION Count () AS LONG

DispObj

Returns a counted reference of the underlying dispatch pointer. You must call IUnknown_Release when no longer needs it.

FUNCTION DispObj () AS ANY PTR

DispPtr

Returns the underlying dispatch pointer. As it is a raw pointer, don’t call IUnknown_Release on it.

FUNCTION DispPtr () AS ANY PTR

Exists

Checks if a specified key exists in the associative array.

FUNCTION Exists (BYREF dvKey AS DVARIANT) AS BOOLEAN

Return value

Returns True is the key exists; False, otherwise.

HashVal

Returns the hash value for a specified key in the associative array.

FUNCTION HashVal (BYREF dvKey AS DVARIANT) AS DVARIANT

Item

Sets or returns an item for a specified key in associative array.

PROPERTY Item (BYREF dvKey AS DVARIANT) AS DVARIANT
PROPERTY Item (BYREF dvKey AS DVARIANT, BYREF dvNewItem AS DVARIANT)

Return value

The item value.

Remarks

If key is not found when changing an item, a new key is created with the specified dvNewvItem. Contrary to the Dictionary object, if key is not found when attempting to return an existing item, it returns and empty variant and sets the last result code to E_INVALIDARG, instead of creating a new key with its corresponding item empty.

Items

Returns a safe array containing all the items in the associative array.

FUNCTION Items () AS DVARIANT

Return value

A DVARIANT containing all the items in a safe array.

Key

Sets or returns an item for a specified key in the associative array.

PROPERTY Key (BYREF dvKey AS DVARIANT, BYREF dvNewKey AS DVARIANT)

Remarks

Contrarily to the Dictionary object, if key is not found when changing a key, this method sets the last result code to E_INVALIDARG and exits, instead of creating a new key with its associated item empty.

Return value

The item value.

Keys

Returns an array containing all the keys in the associative array.

FUNCTION Keys () AS DVARIANT

Return value

A DVARIANT containing all the keys in a safe array.

NewEnum

Returns a reference to the standard enumerator.

FUNCTION NewEnum () AS IEnumVARIANT PTR

Return value

A pointer to the standard IEnumVARIANT interface.

Return value

IUnknown pointer that must be cast to an IEnumVARIANT interface.

Remove

Removes a key, item pair from the associative array.

FUNCTION Remove (BYREF dvKey AS DVARIANT) AS HRESULT

Return value

An error occurs if the specified key, item pair does not exist.

RemoveAll

Removes all key, item pairs from the associative array.

FUNCTION RemoveAll() AS HRESULT

Return value

Returns S_OK (0) or an HRESULT error code.